<!DOCTYPE html>
<html>

  <head>
    <meta charset='utf-8' />
    <meta http-equiv="X-UA-Compatible" content="chrome=1" />
    <meta name="description" content="CAS - Single Sign-On for the Web" />
    
    
    <link rel="stylesheet" type="text/css" media="screen"
          href="../../stylesheets/v40x-stylesheet.css">
    <link rel="stylesheet" type="text/css" media="print"
          href="../../stylesheets/print.css">
    <title>CAS - X.509 Authentication</title>
    <script src="https://ajax.googleapis.com/ajax/libs/jquery/1.10.2/jquery.min.js"></script>
    <script src="../../javascripts/URI.js"></script>
    <script src="../../javascripts/v40x-main.js"></script>
  </head>

  <body>
    <!-- HEADER -->
    <div id="header_wrap" class="outer">
        <header class="inner">
          <a id="forkme_banner" href="https://github.com/Jasig/cas">View on GitHub</a>
          <div id="project_title">
            <a class="undecorated" href="../../index.html">
              <img class="undecorated" src="../../images/cas_logo.png"/>
            </a>
          </div>
          <h2 id="project_tagline">Single Sign-On for the Web</h2>
        </header>
    </div>

    <!-- NAVBAR -->    
    <div id="navbar_wrap" class="outer">
      <header id="navbar_content" class="inner">
        <div class="navlink">
  <a href="../../index.html">Home</a>
</div>
<div class="navlink">
  <a href="https://github.com/Jasig/cas/releases">Downloads</a>
</div>
<div class="navlink">
  <a href="https://www.google.com/cse/publicurl?cx=017040929083740828958:sqr2hwvrxmg">Search</a>
</div>
<div class="navlink">
  <a href="../../Support.html">Support</a>
</div>
<div class="navlink">
  <a href="../../Mailing-Lists.html">Mailing Lists</a>
</div>
<div class="navlink">
  <a href="../../Older-Versions.html">Older Versions</a>
</div>

        </header>
    </div>

      <!-- SIDEBAR -->
      <div id="sidebar_wrap" class="outer">
        <header id="sidebar_content" class="inner">
          <span id="sidebartoc"></span>
        </header >
      </div>
      
      <!-- PAGE TABLE OF CONTENTS -->
      <div id="table_contents" class="outer">
        <header id="sidebar_content" class="inner">
          <span id="tableOfContents"></span>
        </header>
      </div>
      
      <!-- MAIN CONTENT -->
      <div id="main_content_wrap" class="outer">
        <section id="main_content" class="inner">
          <h1 id="x509-authentication">X.509 Authentication</h1>
<p>CAS X.509 authentication components provide a mechanism to authenticate users who present client certificates during
the SSL/TLS handshake process. The X.509 components require configuration ouside the CAS application since the
SSL handshake happens outside the servlet layer where the CAS application resides. There is no particular requirement
on deployment architecture (i.e. Apache reverse proxy, load balancer SSL termination) other than any client
certificate presented in the SSL handshake be accessible to the servlet container as a request attribute named
<code>javax.servlet.request.X509Certificate</code>. This happens naturally for configurations that terminate SSL connections
directly at the servlet container and when using Apache/mod_jk; for other architectures it may be necessary to do
additional work.</p>

<h2 id="x509-components">X.509 Components</h2>
<p>X.509 support is enabled by including the following dependency in the Maven WAR overlay:</p>

<div class="highlight"><pre><code class="xml">    <span class="nt">&lt;dependency&gt;</span>
      <span class="nt">&lt;groupId&gt;</span>org.jasig.cas<span class="nt">&lt;/groupId&gt;</span>
      <span class="nt">&lt;artifactId&gt;</span>cas-server-support-x509<span class="nt">&lt;/artifactId&gt;</span>
      <span class="nt">&lt;version&gt;</span>${cas.version}<span class="nt">&lt;/version&gt;</span>
    <span class="nt">&lt;/dependency&gt;</span>
</code></pre></div>

<p>CAS provides an X.509 authentication handler, a handful of X.509-specific principal resolvers, some certificate
revocation machinery, and some Webflow actions to provide for non-interactive authentication.</p>

<h6 id="x509credentialsauthenticationhandler"><code>X509CredentialsAuthenticationHandler</code></h6>
<p>The X.509 handler technically performs additional checks <em>after</em> the real SSL client authentication process performed
by the Web server terminating the SSL connection. Since an SSL peer may be configured to accept a wide range of
certificates, the CAS X.509 handler provides a number of properties that place additional restrictions on
acceptable client certificates.</p>

<ul>
  <li><code>regExTrustedIssuerDnPattern</code> - Regular expression defining allowed issuer DNs. (must be specified)</li>
  <li><code>regExSubjectDnPattern</code> - Regular expression defining allowed subject DNs. (default=<code>.*</code>)</li>
  <li><code>maxPathLength</code> - Maximum number of certs allowed in certificate chain. (default=1)</li>
  <li><code>maxPathLengthAllowUnspecified</code> - True to allow unspecified path length, false otherwise. (default=false)</li>
  <li><code>checkKeyUsage</code> - True to enforce certificate <code>keyUsage</code> field (if present), false otherwise. (default=false)</li>
  <li><code>requireKeyUsage</code> - True to require the existence of a <code>keyUsage</code> certificate field, false otherwise. (default=false)</li>
  <li><code>revocationChecker</code> - Instance of <code>RevocationChecker</code> used for certificate expiration checks.
(default=<code>NoOpRevocationChecker</code>)</li>
</ul>

<h3 id="principal-resolver-components">Principal Resolver Components</h3>

<h6 id="x509subjectprincipalresolver"><code>X509SubjectPrincipalResolver</code></h6>
<p>Creates a principal ID from a format string composed of components from the subject distinguished name.
The following configuration snippet produces prinicpals of the form <em>cn@example.com</em>. For example, given a
certificate with the subject <em>DC=edu, DC=vt/UID=jacky, CN=Jascarnella Ellagwonto</em> it would produce the ID
<em>jacky@vt.edu</em>.</p>

<div class="highlight"><pre><code class="xml"><span class="nt">&lt;bean</span> <span class="na">id=</span><span class="s">&quot;x509SubjectResolver&quot;</span>
      <span class="na">class=</span><span class="s">&quot;org.jasig.cas.adaptors.x509.authentication.principal.X509SubjectPrincipalResolver&quot;</span>
      <span class="na">p:descriptor=</span><span class="s">&quot;$CN@$DC.$DC&quot;</span> <span class="nt">/&gt;</span>
</code></pre></div>

<p>See the Javadocs for a thorough discussion of the format string specification.</p>

<h6 id="x509subjectdnprincipalresolver"><code>X509SubjectDNPrincipalResolver</code></h6>
<p>Creates a principal ID from the certificate subject distinguished name.</p>

<h6 id="x509serialnumberprincipalresolver"><code>X509SerialNumberPrincipalResolver</code></h6>
<p>Creates a principal ID from the certificate serial number.</p>

<h6 id="x509serialnumberandissuerdnprincipalresolver"><code>X509SerialNumberAndIssuerDNPrincipalResolver</code></h6>
<p>Creates a principal ID by concatenating the certificate serial number, a delimiter, and the issuer DN.
The serial number may be prefixed with an optional string. See the Javadocs for more information.</p>

<h3 id="certificate-revocation-checking-components">Certificate Revocation Checking Components</h3>
<p>CAS provides a flexible policy engine for certificate revocation checking. This facility arose due to lack of
configurability in the revocation machinery built into the JSSE.</p>

<h6 id="resourcecrlrevocationchecker"><code>ResourceCRLRevocationChecker</code></h6>
<p>Performs a certificate revocation check against a CRL hosted at a fixed location. Any resource type supported by the
Spring <a href=""><code>Resource</code></a> class may be specified for the CRL resource. The CRL is fetched at periodic intervals and cached.</p>

<p>Configuration properties:</p>

<ul>
  <li><code>crl</code> - Spring resource describing the location/kind of CRL resource. (must be specified)</li>
  <li><code>refreshInterval</code> - Periodic CRL refresh interval in seconds. (default=3600)</li>
  <li><code>unavailableCRLPolicy</code> - Policy applied when CRL data is unavailable upon fetching. (default=<code>DenyRevocationPolicy</code>)</li>
  <li><code>expiredCRLPolicy</code> - Policy applied when CRL data is expired. (default=<code>ThresholdExpiredCRLRevocationPolicy</code>)</li>
</ul>

<p>The following policies are available by default:</p>

<ul>
  <li><code>AllowRevocationPolicy</code> - Deny policy</li>
  <li><code>DenyRevocationPolicy</code> - Deny policy</li>
  <li><code>ThresholdExpiredCRLRevocationPolicy</code> - Deny if CRL is more than X seconds expired.</li>
</ul>

<p><code>ResourceCRLRevocationChecker</code> Example:</p>

<div class="highlight"><pre><code class="xml"><span class="nt">&lt;bean</span> <span class="na">id=</span><span class="s">&quot;crlResource&quot;</span>
      <span class="na">class=</span><span class="s">&quot;org.springframework.core.io.UrlResource&quot;</span>
      <span class="na">c:path=</span><span class="s">&quot;https://pki.example.com/exampleca/crl&quot;</span> <span class="nt">/&gt;</span>

<span class="nt">&lt;bean</span> <span class="na">id=</span><span class="s">&quot;allowPolicy&quot;</span>
      <span class="na">class=</span><span class="s">&quot;org.jasig.cas.adaptors.x509.authentication.handler.support.AllowRevocationPolicy&quot;</span> <span class="nt">/&gt;</span>

<span class="nt">&lt;bean</span> <span class="na">id=</span><span class="s">&quot;thresholdPolicy&quot;</span>
      <span class="na">class=</span><span class="s">&quot;org.jasig.cas.adaptors.x509.authentication.handler.support.ThresholdExpiredCRLRevocationPolicy&quot;</span>
      <span class="na">p:threshold=</span><span class="s">&quot;3600&quot;</span> <span class="nt">/&gt;</span>

<span class="nt">&lt;bean</span> <span class="na">id=</span><span class="s">&quot;revocationChecker&quot;</span>
      <span class="na">class=</span><span class="s">&quot;org.jasig.cas.adaptors.x509.authentication.handler.support.ResourceCRLRevocationChecker&quot;</span>
      <span class="na">c:crl-ref=</span><span class="s">&quot;crlResource&quot;</span>
      <span class="na">p:refreshInterval=</span><span class="s">&quot;600&quot;</span>
      <span class="na">p:unavailableCRLPolicy-ref=</span><span class="s">&quot;allowPolicy&quot;</span>
      <span class="na">p:thresholdPolicy-ref=</span><span class="s">&quot;thresholdPolicy&quot;</span> <span class="nt">/&gt;</span>
</code></pre></div>

<h6 id="crldistributionpointrevocationchecker"><code>CRLDistributionPointRevocationChecker</code></h6>
<p>Performs certificate revocation checking against the CRL URI(s) mentioned in the certificate <em>cRLDistributionPoints</em>
extension field. The component leverages a cache to prevent excessive IO against CRL endpoints; CRL data is fetched
if does not exist in the cache or if it is expired.</p>

<p>Configuration properties:</p>

<ul>
  <li><code>cache</code> - Ehcache <code>Cache</code> component.</li>
  <li><code>unavailableCRLPolicy</code> - Policy applied when CRL data is unavailable upon fetching. (default=<code>DenyRevocationPolicy</code>)</li>
  <li><code>expiredCRLPolicy</code> - Policy applied when CRL data is expired. (default=<code>ThresholdExpiredCRLRevocationPolicy</code>)</li>
</ul>

<p><code>CRLDistributionPointRevocationChecker</code> Example:</p>

<div class="highlight"><pre><code class="xml"><span class="c">&lt;!-- timeToLive, timeToIdle are in seconds --&gt;</span>
<span class="nt">&lt;bean</span> <span class="na">id=</span><span class="s">&quot;crlCache&quot;</span> <span class="na">class=</span><span class="s">&quot;org.springframework.cache.ehcache.EhCacheFactoryBean&quot;</span>
      <span class="na">p:cacheName=</span><span class="s">&quot;CRLCache&quot;</span>
      <span class="na">p:eternal=</span><span class="s">&quot;false&quot;</span>
      <span class="na">p:overflowToDisk=</span><span class="s">&quot;false&quot;</span>
      <span class="na">p:maxElementsInMemory=</span><span class="s">&quot;100&quot;</span>
      <span class="na">p:timeToLive=</span><span class="s">&quot;36000&quot;</span>
      <span class="na">p:timeToIdle=</span><span class="s">&quot;36000&quot;</span><span class="nt">&gt;</span>
  <span class="nt">&lt;property</span> <span class="na">name=</span><span class="s">&quot;cacheManager&quot;</span><span class="nt">&gt;</span>
    <span class="nt">&lt;bean</span> <span class="na">class=</span><span class="s">&quot;org.springframework.cache.ehcache.EhCacheManagerFactoryBean&quot;</span> <span class="nt">/&gt;</span>
  <span class="nt">&lt;/property&gt;</span>
<span class="nt">&lt;/bean&gt;</span>

<span class="nt">&lt;bean</span> <span class="na">id=</span><span class="s">&quot;denyPolicy&quot;</span>
      <span class="na">class=</span><span class="s">&quot;org.jasig.cas.adaptors.x509.authentication.handler.support.DenyRevocationPolicy&quot;</span> <span class="nt">/&gt;</span>

<span class="nt">&lt;bean</span> <span class="na">id=</span><span class="s">&quot;thresholdPolicy&quot;</span>
      <span class="na">class=</span><span class="s">&quot;org.jasig.cas.adaptors.x509.authentication.handler.support.ThresholdExpiredCRLRevocationPolicy&quot;</span>
      <span class="na">p:threshold=</span><span class="s">&quot;3600&quot;</span> <span class="nt">/&gt;</span>

<span class="nt">&lt;bean</span> <span class="na">id=</span><span class="s">&quot;revocationChecker&quot;</span>
      <span class="na">class=</span><span class="s">&quot;org.jasig.cas.adaptors.x509.authentication.handler.support.CRLDistributionPointRevocationChecker&quot;</span>
      <span class="na">c:cache-ref=</span><span class="s">&quot;crlCache&quot;</span>
      <span class="na">p:unavailableCRLPolicy-ref=</span><span class="s">&quot;denyPolicy&quot;</span>
      <span class="na">p:thresholdPolicy-ref=</span><span class="s">&quot;thresholdPolicy&quot;</span> <span class="nt">/&gt;</span>
</code></pre></div>

<h3 id="webflow-components">Webflow Components</h3>
<p>A single Webflow component, <code>X509CertificateCredentialsNonInteractiveAction</code>, is required to extract the certificate
from the HTTP request context and perform non-interactive authentication.</p>

<h2 id="x509-configuration">X.509 Configuration</h2>
<p>X.509 configuration requires substantial configuration outside the CAS Web application. The configuration of Web
server SSL components varies dramatically with software and is outside the scope of this document. We offer some
general advice for SSL configuration:</p>

<ul>
  <li>Configuring SSL components for optional client certificate behavior generally provides better user experience.
Requiring client certificates prevents SSL negotiation in cases where the certificate is not present, which prevents
user-friendly server-side error messages.</li>
  <li>Accept certificates only from trusted issuers, generally those within your PKI.</li>
  <li>Specify all certificates in the certificate chain(s) of allowed issuers.</li>
</ul>

<h3 id="configure-authentication-components">Configure Authentication Components</h3>
<p>Use the following template to configure authentication in <code>deployerConfigContext.xml</code>:</p>

<div class="highlight"><pre><code class="xml"><span class="nt">&lt;bean</span> <span class="na">id=</span><span class="s">&quot;crlResource&quot;</span>
      <span class="na">class=</span><span class="s">&quot;org.springframework.core.io.UrlResource&quot;</span>
      <span class="na">c:path=</span><span class="s">&quot;https://pki.example.com/exampleca/crl&quot;</span> <span class="nt">/&gt;</span>

<span class="nt">&lt;bean</span> <span class="na">id=</span><span class="s">&quot;allowPolicy&quot;</span>
      <span class="na">class=</span><span class="s">&quot;org.jasig.cas.adaptors.x509.authentication.handler.support.AllowRevocationPolicy&quot;</span> <span class="nt">/&gt;</span>

<span class="nt">&lt;bean</span> <span class="na">id=</span><span class="s">&quot;thresholdPolicy&quot;</span>
      <span class="na">class=</span><span class="s">&quot;org.jasig.cas.adaptors.x509.authentication.handler.support.ThresholdExpiredCRLRevocationPolicy&quot;</span>
      <span class="na">p:threshold=</span><span class="s">&quot;3600&quot;</span> <span class="nt">/&gt;</span>

<span class="nt">&lt;bean</span> <span class="na">id=</span><span class="s">&quot;revocationChecker&quot;</span>
      <span class="na">class=</span><span class="s">&quot;org.jasig.cas.adaptors.x509.authentication.handler.support.ResourceCRLRevocationChecker&quot;</span>
      <span class="na">c:crl-ref=</span><span class="s">&quot;crlResource&quot;</span>
      <span class="na">p:refreshInterval=</span><span class="s">&quot;600&quot;</span>
      <span class="na">p:unavailableCRLPolicy-ref=</span><span class="s">&quot;allowPolicy&quot;</span>
      <span class="na">p:thresholdPolicy-ref=</span><span class="s">&quot;thresholdPolicy&quot;</span> <span class="nt">/&gt;</span>

<span class="nt">&lt;bean</span> <span class="na">id=</span><span class="s">&quot;x509Handler&quot;</span>
      <span class="na">class=</span><span class="s">&quot;org.jasig.cas.adaptors.x509.authentication.handler.support.X509CredentialsAuthenticationHandler&quot;</span>
      <span class="na">p:trustedIssuerDnPattern=</span><span class="s">&quot;CN=(DEV )*Virginia Tech [A-Za-z ]*User CA.*&quot;</span>
      <span class="na">p:maxPathLength=</span><span class="s">&quot;2147483647&quot;</span>
      <span class="na">p:maxPathLengthAllowUnspecified=</span><span class="s">&quot;true&quot;</span>
      <span class="na">p:checkKeyUsage=</span><span class="s">&quot;true&quot;</span>
      <span class="na">p:requireKeyUsage=</span><span class="s">&quot;true&quot;</span>
      <span class="na">p:revocationChecker-ref=</span><span class="s">&quot;revocationChecker&quot;</span><span class="nt">&gt;</span>      

<span class="nt">&lt;bean</span> <span class="na">id=</span><span class="s">&quot;x509PrincipalResolver&quot;</span>
      <span class="na">class=</span><span class="s">&quot;org.jasig.cas.adaptors.x509.authentication.principal.X509SubjectPrincipalResolver&quot;</span>
      <span class="na">p:descriptor=</span><span class="s">&quot;$UID&quot;</span> <span class="nt">/&gt;</span>

<span class="nt">&lt;bean</span> <span class="na">id=</span><span class="s">&quot;authenticationManager&quot;</span>
      <span class="na">class=</span><span class="s">&quot;org.jasig.cas.authentication.PolicyBasedAuthenticationManager&quot;</span><span class="nt">&gt;</span>
  <span class="nt">&lt;constructor-arg&gt;</span>
    <span class="nt">&lt;map&gt;</span>
      <span class="nt">&lt;entry</span> <span class="na">key-ref=</span><span class="s">&quot;x509Handler&quot;</span> <span class="na">value-ref=</span><span class="s">&quot;x509PrincipalResolver&quot;</span><span class="nt">/&gt;</span>
    <span class="nt">&lt;/map&gt;</span>
  <span class="nt">&lt;/constructor-arg&gt;</span>
  <span class="nt">&lt;property</span> <span class="na">name=</span><span class="s">&quot;authenticationMetaDataPopulators&quot;</span><span class="nt">&gt;</span>
    <span class="nt">&lt;list&gt;</span>
      <span class="nt">&lt;bean</span> <span class="na">class=</span><span class="s">&quot;org.jasig.cas.authentication.SuccessfulHandlerMetaDataPopulator&quot;</span> <span class="nt">/&gt;</span>
    <span class="nt">&lt;/list&gt;</span>
  <span class="nt">&lt;/property&gt;</span>
<span class="nt">&lt;/bean&gt;</span>
</code></pre></div>

<h3 id="x509-webflow-configuration">X.509 Webflow Configuration</h3>
<p>Uncomment the <code>startAuthenticate</code> state in <code>login-webflow.xml</code>:</p>

<div class="highlight"><pre><code class="xml"><span class="nt">&lt;action-state</span> <span class="na">id=</span><span class="s">&quot;startAuthenticate&quot;</span><span class="nt">&gt;</span>
  <span class="nt">&lt;action</span> <span class="na">bean=</span><span class="s">&quot;x509Check&quot;</span> <span class="nt">/&gt;</span>
  <span class="nt">&lt;transition</span> <span class="na">on=</span><span class="s">&quot;success&quot;</span> <span class="na">to=</span><span class="s">&quot;sendTicketGrantingTicket&quot;</span> <span class="nt">/&gt;</span>
  <span class="nt">&lt;transition</span> <span class="na">on=</span><span class="s">&quot;warn&quot;</span> <span class="na">to=</span><span class="s">&quot;warn&quot;</span> <span class="nt">/&gt;</span>
  <span class="nt">&lt;transition</span> <span class="na">on=</span><span class="s">&quot;error&quot;</span> <span class="na">to=</span><span class="s">&quot;generateLoginTicket&quot;</span> <span class="nt">/&gt;</span>
<span class="nt">&lt;/action-state&gt;</span>
</code></pre></div>

<p>Replace all instances of the <code>generateLoginTicket</code> transition in other states with <code>startAuthenticate</code>.</p>

<p>Define the <code>x509Check</code> bean in <code>cas-servlet.xml</code>:</p>

<div class="highlight"><pre><code class="xml"><span class="nt">&lt;bean</span> <span class="na">id=</span><span class="s">&quot;x509Check&quot;</span>
   <span class="na">class=</span><span class="s">&quot;org.jasig.cas.adaptors.x509.web.flow.X509CertificateCredentialsNonInteractiveAction&quot;</span>
   <span class="na">p:centralAuthenticationService-ref=</span><span class="s">&quot;centralAuthenticationService&quot;</span> <span class="nt">/&gt;</span>
</code></pre></div>


        </section>
      </div>

    <!-- FOOTER  -->
    <div id="footer_wrap" class="outer">
      <footer class="inner">
        <p>CAS is supported by the <a href="http://www.apereo.org/">Apereo Foundation</a>.</p>
      </footer>
    </div>
  </body>
</html>
